Tangible Software Solutions
Instant VB Help
Contents
- Project & Folder Conversion
- File & Snippet Conversion
- Command Line Conversion
- Code Formatting Options
- Conversion Message Options
- Custom String Replacements
- Diagnostic Options
- File Encoding Options
- Project Conversion Groups
- Default Shared Assemblies for Conversions
- Assumed Imported Namespaces for Snippet Conversions
- Project Conversion Options
- Additions & Omissions
- Miscellaneous Options
- Assembly Resolution
Project & Folder Conversion
The Project & Folder Converter tab allows you to convert
all C# code within a project, solution, or folder. Once the conversion is finished, you can then
launch the new project or solution, view Instant VB comments, compare converted code files
to original code files, and view the new project or solution folder.
The folder conversion option allows you to convert all C# code within a folder hierarchy.
The Conversion History listview displays previously converted projects and allows you
to launch the project, view remaining Instant VB comments, and view the project folder.
File & Snippet Conversion
The File & Snippet Converter tab allows you to convert
C# code snippets or files. From the left side textbox, you can type or paste code
snippets, insert files, or view Instant VB sample snippets. Once a file or
snippet is converted, you can select and copy the results, save the results to a file,
or search the results.
Command Line Conversion
Instant VB can be launched from the command line with one
or two parameters plus an optional last parameter indicating the location of a
conversion options file. If only one parameter is specified, it is interpreted as the
name of one of your custom project conversion groups. If two parameters are specified,
the first parameter is either a C# project file, solution file, folder, or file that you
wish to convert, and the second parameter is the folder or file that the converted VB
project will be written to. If the optional last parameter indicating the location of a conversion options file is included, then
that file is imported before the conversion starts. A conversion options file
has the extension '.opt' and is produced by exporting existing options to an xml file from the converter.
e.g. (project group conversion),
"Instant VB" "MyProjectGroup"
e.g. (single project conversion),
"Instant VB" "C:\C# Projects\Sample Project.csproj" "C:\VB Projects\Sample Target Folder"
e.g. (solution conversion),
"Instant VB" "C:\C# Projects\Sample Solution.sln" "C:\VB Projects\Sample Target Folder"
e.g. (folder conversion),
"Instant VB" "C:\C# Projects\Sample Source Folder" "C:\VB Projects\Sample Target Folder"
e.g. (file conversion),
"Instant VB" "C:\C# Source Files\testfile.cs" "C:\VB Converted Files\testfile.vb"
e.g. (folder conversion with a conversion options file specified),
"Instant VB" "C:\C# Projects\Sample Source Folder" "C:\VB Projects\Sample Target Folder" "C:\Options\Instant VB.opt"
Once the command line conversion is complete, Instant VB will shut down.
Note that Instant VB must be in double quotes since the executable name contains a space.
- Indentation: You can choose whether the
converted code uses tabs or spaces for the leading white space. If you choose
tabs for leading white space, then leading spaces in the original code of the length
that you specify are replaced by tabs. If you choose spaces for leading white space,
then tabs in the original code are replaced by spaces of the length that you specify.
- Arrays:
VB allows you to include the array specifer in variable
declarations either after the variable name or after the variable type
(e.g., Dim myArray() As ThisType or Dim myArray As ThisType()).
You have the option of enforcing either standard in the conversion produced
by Instant VB. You can also choose short-form vs.
long-form array initialization - e.g., Dim x(5) As Foo instead of Dim x() As Foo = New Foo(5){}.
The short-form is the default.
- Nullable Syntax: VB allows you to include the
nullable token ? in variable declarations either after the variable name
or after the variable type (e.g., Dim myNullable? As ThisType or
Dim myNullable As ThisType?). You have the option of enforcing either standard
in the conversion produced by Instant VB. The nullable token ? is only
applicable to VB9 or later.
You can also choose to use the longer syntax which explicitly states the type
(e.g., Dim myNullable As Nullable(Of Boolean)).
- Control Statements: If you
select this option, the converter will break apart control structure statements
(if and while statements) by the main conditions. See the output in the
textbox to see the effect of this option.
- Method Declarations: If you select this
option, the converter will break apart method declarations by the method parameters. See the
output in the textbox to see the effect of this option.
- Method Calls: If you select this
option, the converter will break apart method calls by the method call arguments. See the
output in the textbox to see the effect of this option.
- String Literal Concatenation: If you select this
option, the converter will break apart multiple string literal concatenations to separate
lines. See the output in the textbox to see the effect of this option.
- LINQ:
- Start LINQ queries on a new line: Selecting this
option causes Instant VB to format LINQ queries so that the starting From
appears on a new line.
- Break LINQ queries on keywords: Selecting this
option causes Instant VB to format LINQ queries so that the keywords Where,
From, Select, Group, Join, Order By,
Let, Skip, and Take begin new lines.
- Other:
- Use single-line 'If' statements: Selecting this
option causes Instant VB to use the single-line If statement format
(e.g., If SomeCondition Then PerformAction()).
- Shorten declarations to 'As New': Instant VB will
convert variable declarations containing constructor calls to this short form if this
preference is checked: e.g., Dim x As New Foo() instead of Dim x As Foo = New Foo().
The default is the shorter form.
- Use implicit line continuations: VB10 or later allows
omitting the underscore line continuation in most cases. If you select this option,
the conversion output will omit line continuations (since the converter doesn't usually
break up lines, this mainly applies to attributes and array or collection initializers).
- Add 'For' loop variable names to the closing 'Next' statements:
It's optional to have the For loop variable name tagged to the end of the
Next statement. Instant VB adds it by default.
- Omit parentheses on default constructor calls: Selecting
this option causes Instant VB to drop empty argument lists on default constructor calls,
which is preferred by some VB programmers (e.g., "New Foo()" becomes "New Foo").
- Omit the 'ByVal' specifier for parameters: VB10 or later allows
omitting the ByVal specifier on parameters.
Instant VB will insert it unless you choose to omit it.
- Use generous line spacing: Selecting this option
causes Instant VB to add blank lines at the beginning and end of all control structures
and block declarations (wherever a brace may have appeared in the original C# code).
- Omit parentheses on property declarations: Selecting
this option causes Instant VB to drop empty argument lists on property declarations,
which is preferred by some VB programmers (e.g., "Property Foo() As Integer" becomes
"Property Foo As Integer").
Conversion Message Options
On this options dialog, you can customize the comment prefixes
that the converter uses for messages and also toggle the messages that Instant VB
displays on or off.
You can easily set all or none to display via the 'Select All' and 'Select None' buttons.
Custom String Replacements
Instant VB allows you to specify your own custom replacements
in the converted VB code. This can be useful for customizing code according to style
preferences that may be different in VB than in C#. It's also useful for cases where
a C# method without a good VB equivalent will be replaced by your own custom method to be
called from the converted code.
For each replacement string you can specify the regex option, when to perform the replacement
(pre or post conversion), whether or not to match case, whether to match whole words only,
and whether comments or string literals should be modified. The whole words and string literals
options do not apply if the regex option is selected.
To span mulitple lines, either paste directly into the 'Find' and 'Replacement'
textboxes, or use the escaped characters: \r\n\t.
The "Active" checkbox can be unchecked if you wish to temporarily bypass the replacement.
Replacements are made in the order that they appear on the options dialog. For example,
the second replacement is made to each line of code after the first replacement has already
been made. To change the order of replacements, use the 'Up' and 'Down' buttons.
For an example of the regex option, you could do a custom replacement of "Foo(x)" with "Bar(x)",
where "x" is any argument, by specifying the "Find" field as "Foo(([\sa-zA-Z_$]*))" and the
"Replace" field as "Bar$1". Note that there are differences in various regex engines - the
regex engine used by the converter is .NET System.Text.RegularExpressions.Regex.
Diagnostic Options
These options are intended to provide information to
Tangible Software Solutions if a conversion is taking longer than expected.
'Record processing by file' instructs the converter to make a record of the files
processed and the time taken for each process. 'Record the last 100 lines of code
parsed before cancelling conversion' instructs the converter to make a record of the
most recent lines parsed before you cancelled the conversion.
File Encoding Options
The converter detects input file encoding from the byte order
mark (BOM), but if the BOM is missing the converter assumes by default that the file encoding
is UTF-8. You can use this option to specify a different default encoding to use in the absence
of a BOM. Output is written in the same encoding as the encoding detected for the original file,
or your default encoding option if the original coding was not detected via the BOM.
For UTF-8, you can choose whether or not to include the BOM for the output - this is normally
used in Windows environments.
Project Conversion Groups
If you need to regularly convert many projects at the same time,
use the Conversion Groups feature. This is most commonly used to convert sets of sample
projects to VB.
To configure Conversion Groups, go to Options->Project Conversion Groups on the main menu
or toolbar.
To convert a Conversion Group, go to Convert->Convert Group on the main menu.
Default Shared Assemblies for Conversions
For snippet and folder conversions, you can specify the
assemblies that the converter should resolve when interpreting the original code.
For .NET Core SDK projects, the project file contains no information about the shared
assemblies used by the project. The converter will not automatically attempt to resolve
every assembly in the .NET Core shared assembly location since it takes time to resolve the type
information in each assembly. Instead, we resolve only the shared assembly defining the core types
(System.Private.CoreLib) and allow you to select other assemblies for each project SDK that
you typically use.
For .NET Framework SDK projects, the project file contains no information about the GAC
assemblies used by the project. The converter will not automatically attempt to resolve
every assembly in the .NET Framework GAC assembly location since it takes time to resolve the type
information in each assembly. Instead, we resolve only the GAC assemblies 'mscorlib' and
'System' and allow you to select other assemblies for each project SDK that
you typically use.
Assumed Imported Namespaces for Snippet Conversions
You can specify namespaces that you would like the snippet converter
to assume are available when interpreting the original code. The snippet converter will then
convert as if the snippet contained the corresponding 'using' directives.
Project Conversion Options
- Add standard project-level imports: By default,
Instant VB will add the standard project-level imports to the converted project
(e.g., System, System.Data, etc.). If you prefer to not have any project-level
imports then uncheck this. This option does not apply to SDK projects, such as .NET Core projects.
- Bypass assembly resolution dialogs: By default,
Instant VB prompts you for the location of assembly dll's that it cannot find - this
aids in identifying the best conversion for some references to these assemblies.
Also, Instant VB will display message boxes if it cannot resolve the types or members
within an assembly. Select this option if you do not want to see these dialogs.
- Reproduce project integer overflow setting: By default,
Instant VB will reproduce the same integer overflow settings as the original C# project.
For VB projects, this is called 'RemoveIntegerChecks' and for C# projects, this is called
'CheckForOverflowUnderflow'. Since these are opposite in meaning, the values in the project
file are reversed. If you uncheck this option, the default VB behavior of checking for
integer overflow will be in effect for the converted project.
- Use the C# 'default namespace' as the VB 'root namespace':
By default, Instant VB reproduces the namespace statements found in the original C# code.
If you select this option, Instant VB will remove namespace statements corresponding to
the C# 'default namespace' and set the VB project-level 'root namespace' to the
C# default namespace. C# types that were not contained in the default namespace are added to
the VB 'Global' namespace (so that they continue to exist outside of the VB root namespace).
Additions & Omissions
- Add to the top of all converted files: If you add text
for this option, that text will be added to the top of every converted file. This option
does not apply to code snippet conversions.
- Omit code regions for these preprocessor tokens:
Instant VB will remove regions of code from the conversion output which are
in preprocessor blocks positively conditional on any of these tokens (e.g., #if OMIT).
- Copy code unconverted for these preprocessor tokens:
Instant VB will leave regions of code unconverted which are in preprocessor
blocks positively conditional on any of these tokens (e.g., #if COPY). Any #elif or
#else blocks following the #if section are removed from the conversion output.
Miscellaneous Options
- Renaming tag for code element conflicts: Instant VB
must occasionally rename code elements to avoid conflicts. You can choose your own renaming
tag and whether to place it at the beginning or end of the original name when this is necessary.
- Conversion of carriage return + line feed: By default
Instant VB converts "\r\n" to vbCrLf (exactly equivalent), but you may prefer
ControlChars.CrLf (also exactly equivalent) or Environment.NewLine (not always equivalent,
but sometimes preferred). Note that vbNewLine and ControlChars.NewLine
are deprecated.
- Convert .NET Trim/TrimStart/TrimEnd to the VB Trim/LTrim/RTrim functions:
By default Instant VB preserves all .NET method calls, but you have the option of
converting the .NET Trim, TrimStart, and TrimEnd methods to the VB Trim, LTrim, and RTrim
functions. Be aware that the VB methods may not produce identical results in all scenarios.
- Convert .NET ToLower/ToUpper to the VB LCase/UCase functions:
By default Instant VB preserves all .NET method calls, but you have the option of
converting the .NET ToLower and ToUpper methods to the VB LCase and UCase
functions. Be aware that the VB methods may not produce identical results in all scenarios.
- Convert .NET ToString to the VB CStr cast:
By default Instant VB preserves ToString method calls, but you have the option of
converting .NET ToString method calls to the VB CStr cast. Be aware that this
may not produce identical results in all scenarios.
- Convert .NET String.Length to the VB Len function:
By default Instant VB preserves use of String.Length, but you have the option of
converting the .NET String.Length method to the VB Len function. Be aware that this may
not produce identical results in all scenarios.
- Convert System.Convert method calls to VB casts:
By default Instant VB preserves all System.Convert method calls, but you have the
option of converting these to the instrinsic VB casts. Be aware that the VB casts
may not produce identical results in all scenarios.
- Convert Parse method calls to VB casts:
By default Instant VB preserves all of the various type Parse method calls
(e.g., Boolean.Parse), but you have the option of converting these to the
instrinsic VB casts. Be aware that the VB casts may not produce identical results
in all scenarios.
- Convert static classes to modules: By default
Instant VB converts a C# static class to a VB Module, but you have the
option of converting these to NotInheritable classes with a private constructor
to prevent instantiation.
- Check for control handle creation in WinForms event methods using 'Handles':
By default Instant VB exits event methods using 'Handles' if the WinForms event field is still being
initialized in the InitializeComponent method, but you can choose to omit this check.
Assembly Resolution
Assemblies referenced by projects are examined to
determine the nature of the types and members within the assembly to improve the conversion
quality.
During the project conversion process you may be prompted
by the converter to find specific assemblies referenced by your project if they
cannot otherwise be found by the converter.
If the converter does not resolve all assemblies, you can still
continue the project conversion, but the conversion may not be optimal for code which
references the unresolved assemblies. This just means that a few more manual adjustments
may be required.
If the assembly does not require an install, you can forward it
to us in a zip file to determine why it is not resolving.
Copyright © Tangible Software Solutions, Inc.